<SearchBox> (React InstantSearch v7)

The searchBox widget lets users perform a text-based query.

The search box is usually the main entry point to start the search on an InstantSearch page. It’s usually placed at the top of a search experience, so users can start searching right away.

<SearchBox
    // Optional parameters
    placeholder,
    autofocus,
    ignoreCompositionEvents,
    searchAsYouType,
    onSubmit,
    submitIconComponent,
    resetIconComponent,
    showLoadingIndicator,
    queryHook,
    templates,
    cssClasses
/>

<SearchBox
    // Optional parameters
    placeholder,
    autofocus,
    ignoreCompositionEvents,
    searchAsYouType,
    onSubmit,
    submitIconComponent,
    resetIconComponent,
    showLoadingIndicator,
    queryHook,
    templates,
    cssClasses
/>

import React from 'react';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, SearchBox } from 'react-instantsearch';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App() {
    return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
        <SearchBox />
    </InstantSearch>
    );

Demo

Import

import { SearchBox } from 'react-instantsearch';

Props

placeholder

string

The placeholder text of the input.

<SearchBox placeholder="Search for products" />

autofocus

boolean

default:"false"

Whether to automatically focus on the input when rendered.

<SearchBox autoFocus />

ignoreCompositionEvents

boolean

default:"false"

Whether to update the search state in the middle of a composition session. This is useful when users need to search using non-Latin characters.

<SearchBox ignoreCompositionEvents />

Available from v7.5.4.

searchAsYouType

boolean

default:"true"

Whether to make a search on every change to the query. If false, new searches are only triggered by clicking the search button or by pressing the Enter key in the search box.

<SearchBox searchAsYouType={false} />

onSubmit

(event: React.FormEvent<HTMLFormElement>) => void

A callback function to run when submitting the search box form.

<SearchBox
onSubmit={(event) => {
    // Code to run when the form submits
}}
/>

submitIconComponent

(props: IconProps) => JSX.Element

A component to replace the submit button icon.

The component receives the passed classNames prop.

<SearchBox
    submitIconComponent={({ classNames }) => (
        <div className={classNames.submitIcon}>Submit</div>
    )}
/>

resetIconComponent

(props: IconProps) => JSX.Element

A component to replace the reset button icon.

The component receives the passed classNames prop.

<SearchBox
    resetIconComponent={({ classNames }) => (
        <div className={classNames.resetIcon}>Reset</div>
    )}
/>

loadingIconComponent

(props: IconProps) => JSX.Element

A component to replace the loading icon.

The component receives the passed classNames prop.

<SearchBox
    loadingIconComponent={({ classNames }) => (
        <div className={classNames.loadingIcon}>Loading</div>
    )}
/>

queryHook

(query: string, search: (value: string) => void) => void

A function that’s called just before the search is triggered. It takes two parameters:

query: string: the current query string
search: function: a function to trigger the search.

If the search method isn’t called, no search is made to Algolia and the UI doesn’t refresh. If the search method is called, the widget is rendered.

This can be useful if you need to:

Debounce searches to regulate requests.
Programmatically alter the query before sending it to Algolia.

When using this prop, you’re responsible for triggering the search with search(). If you don’t call this function, no search is sent to Algolia.

const queryHook = (query, search) => {
    search(query);
};

function Search() {
    return <SearchBox queryHook={queryHook} />;
}

classNames

Partial<SearchBoxClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

root: the root element of the widget.
form: the form element.
input: the input element.
submit: the submit button.
reset: the reset button.
loadingIndicator: the loading indicator element.
submitIcon: the submit icon.
resetIcon: the reset icon.
loadingIcon: the loading icon.

<SearchBox
    classNames={{
        root: 'MyCustomSearchBox',
        form: 'MyCustomSearchBoxForm MyCustomSearchBoxForm--subclass',
    }}
/>

translations

Partial<SearchBoxTranslations>

A dictionary of translations to customize the UI text and support internationalization.

submitButtonTitle: the submit button’s title.
resetButtonTitle: the reset button’s title.

<SearchBox
    translations={{
        submitButtonTitle: 'Search',
        resetButtonTitle: 'Reset',
    }}
/>

...props

React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

<SearchBox className="MyCustomSearchBox" title="My custom title" />

Hook

React InstantSearch lets you create your own UI for the <SearchBox> widget with useSearchBox(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useSearchBox() Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Create your React component

import { useSearchBox } from 'react-instantsearch';

function CustomSearchBox(props) {
const {
    query,
    refine,
    clear,
    // Deprecated
    isSearchStalled,
} = useSearchBox(props);

return <>{/* Your JSX */}</>;
}

Render the widget

<CustomSearchBox {...props} />

Hook parameters

Hooks accept parameters. You can pass them manually or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

queryHook

(query: string, search: (value: string) => void) => void

Function called every time the query changes.

For more information, see the queryHook prop.

const queryHook = (query, search) => {
search(query);
};

function SearchBox() {
const searchBoxApi = useSearchBox({
    // ...
    queryHook,
});

return <>{/* Your JSX */}</>;
}

Hook APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

query

string

The query from the last search.

refine

(value: string) => void

Sets a new query and searches.

clear

() => void

Clears the query and searches.

isSearchStalled

boolean

deprecated

Whether the search results take more than a certain time to come back from Algolia servers.

This can be configured on <InstantSearch> with the stalledSearchDelay prop which defaults to 200 ms.

This API is deprecated. Use status from useInstantSearch() instead.

Hook example

import React, { useState, useRef } from 'react';
import { useInstantSearch, useSearchBox } from 'react-instantsearch';

function CustomSearchBox(props) {
    const { query, refine } = useSearchBox(props);
    const { status } = useInstantSearch();
    const [inputValue, setInputValue] = useState(query);
    const inputRef = useRef(null);

    const isSearchStalled = status === 'stalled';

    function setQuery(newQuery) {
    setInputValue(newQuery);

    refine(newQuery);
    }

    return (
    <div>
        <form
        action=""
        role="search"
        noValidate
        onSubmit={(event) => {
            event.preventDefault();
            event.stopPropagation();

            if (inputRef.current) {
            inputRef.current.blur();
            }
        }}
        onReset={(event) => {
            event.preventDefault();
            event.stopPropagation();

            setQuery('');

            if (inputRef.current) {
            inputRef.current.focus();
            }
        }}
        >
        <input
            ref={inputRef}
            autoComplete="off"
            autoCorrect="off"
            autoCapitalize="off"
            placeholder="Search for products"
            spellCheck={false}
            maxLength={512}
            type="search"
            value={inputValue}
            onChange={(event) => {
            setQuery(event.currentTarget.value);
            }}
            autoFocus
        />
        <button type="submit">Submit</button>
        <button
            type="reset"
            hidden={inputValue.length === 0 || isSearchStalled}
        >
            Reset
        </button>
        <span hidden={!isSearchStalled}>Searching…</span>
        </form>
    </div>
    );
}

UI libraries

InstantSearch

Demo

​Import

​Props

​Hook

​Hook parameters

​Hook APIs

​Hook example

Import

Props

Hook

Hook parameters

Hook APIs

Hook example